From 427c3f4a53fe70799b08ff49c23ddd41ab2376c6 Mon Sep 17 00:00:00 2001
From: Justin Burkett <justin@burkett.cc>
Date: Sun, 18 Oct 2020 15:34:53 -0400
Subject: [PATCH] Clarify README's description of keymap-based replacement

---
 README.org | 66 ++++++++++++++++++++++++++++--------------------------
 1 file changed, 34 insertions(+), 32 deletions(-)

diff --git a/README.org b/README.org
index 92745fff308..d2d375d3a98 100644
--- a/README.org
+++ b/README.org
@@ -257,47 +257,49 @@
 *** Custom String Replacement Options
     #+NAME: #custom-string-replacement-options
     You can customize the way the keys show in the buffer using three different
-    replacement methods, each of which corresponds replacement alist. The basic
-    idea of behind each alist is that you specify a selection string in the
-    =car= of each cons cell and the replacement string in the =cdr=.
+    replacement methods. The first, keymap-based replacement, is preferred and
+    will take precedence over the others. The remaining methods are still
+    available, because they pre-date the first and are more flexible in what
+    they can accomplish.
 
-**** Automatic ("keymap-based") replacement
-     A newer option is to set =which-key-enable-extended-define-key= which
-     advises =define-key= to allow which-key to pre-process its arguments. With
-     this option enabled, the statement
+**** Keymap-based replacement
+     Using this method, which-key can display a custom string for a key
+     definition in some keymap. There are two ways to define a keymap-based
+     replacement. The first is to use
+     =which-key-add-keymap-based-replacements=. The statement
 
      #+BEGIN_SRC emacs-lisp
-     (define-key some-map "f" '("foo" . command-foo))
+       (define-key some-map "f" 'long-command-name-foo)
+       (define-key some-map "b" some-prefix-map)
+       (which-key-add-keymap-based-replacements some-map
+         "f" '("foo" . long-command-name-foo)
+         ;; or
+         ;; "f" "foo" (see the docstring)
+         "b" '("bar-prefix")
+         ;; or
+         ;; "b" "bar-prefix" (see the docstring)
+       )
      #+END_SRC
 
-     will both bind the command =command-foo= to "f" in =some-map= and tell
-     which-key to use the string "foo" for this command. This also works with
-     naming prefixes if you use =nil= for the command. The following binds "b"
-     to =nil= and names the binding as a prefix.
+     uses =define-key= to add two bindings and tells which-key to use the string
+     "foo" in place of "command-foo" and the string "bar-prefix" for
+     some-prefix-map. Note that =which-key-add-keymap-based-replacements= will
+     not bind a command, so =define-key= must still be used.
 
-     #+BEGIN_SRC emacs-lisp
-     (define-key some-map "b" '("bar-prefix"))
-     #+END_SRC
-
-     If you do not want to enable the advise on =define-key=, you may also use
-     =which-key-add-keymap-based-replacements=. The first example can be
-     alternatively written as
+     Alternatively, you may set =which-key-enable-extended-define-key= to =t=
+     before loading which-key and accomplish the same effect using only
+     =define-key= as follows.
 
      #+BEGIN_SRC emacs-lisp
-     (define-key some-map "f" 'command-foo)
-     (define-key some-map "b" some-prefix-map)
-     (which-key-add-keymap-based-replacements some-map
-       "f" '("foo" . long-name-for-command-foo)
-       ;; or
-       ;; "f" "foo"
-       "b" '("bar-prefix")
-       ;; or
-       ;; "b" "bar-prefix"
-     )
+     (define-key some-map "f" '("foo" . command-foo))
+     (define-key some-map "b" '("bar-prefix"))
      #+END_SRC
 
-     Note that =which-key-add-keymap-based-replacements= will not bind a
-     command, so =define-key= must still be used.
+     The option =which-key-enable-extended-define-key= advises =define-key= to
+     allow which-key to use the =(NAME . COMMAND)= notation to simultaneously
+     define a command and give that command a name using =define-key=. Since
+     many key-binding utilities use =define-key= internally, this functionality
+     should be available with your favorite method of defining keys as well.
 
      There are other methods of telling which-key to replace command names,
      which are described next. The keymap-based replacements should be the most
@@ -306,7 +308,7 @@
      replace text. They can be used simultaneously, but which-key will give
      precedence to the keymap-based replacement when it exists.
 
-**** "Key-Based" replacement
+**** Key-Based replacement
      Using this method, the description of a key is replaced using a string that
      you provide. Here's an example
 
-- 
2.30.2